Back to Contents Previous Next
21. Plotting text on the screen
You should, by now, be able to plot sprites, drawfiles and JPEG files in a window, using PROCuser_redraw
. DrWimp provides similar facilities to plot text in a variety of ways directly onto a window or the screen, using ‘outline fonts’.
Choosing and defining a font
Before plotting text it is necessary to decide which outline font is to be used - and at what size and colour. Dr Wimp imposes no restrictions here.
Dr Wimp allows a font to be specified as a name or as a ‘font handle’ - by conveniently providing complementary pairs of wimp-functions, as will be seen below.
Font names
Those wimp-functions requiring the name of the font use a string descriptor in what is called the ‘period separated’ form. For example:
"Trinity.Medium"
"Homerton.Bold.Oblique"
"Corpus.Medium.Oblique"
i.e. there are periods (full stops) between each part - conforming with font file naming, in fact.
Font handles
Those text-plotting wimp-functions requiring a font handle need to be preceded by the use of a call to FNwimp_getfont()
, such as:
fonthandle%=FNwimp_getfont(font$,pointsizex,pointsizey)
where font$
is the period-separated font name (as described above) and pointsizex
, pointsizey
are the required font width and height in points. Note that these latter two are not integer parameters, so decimal values can be used.
The return is the font handle - here, fonthandle%
- which is unique to the specific font name/size combination. If the font name cannot be found (most usually because the named font is not present on your computer) the return will be 0 and you will need to take account of this and perhaps arrange for one of the RISCOS standard fonts to be used instead and warning the user accordingly.
It is often best to call FNwimp_getfont()
during an application’s initialisation i.e. inside DEF PROCuser_initialise
, for each of the font/size combinations which are going to be used. Thus providing a set of font handles from the start.
If you have not come across font handles before it is probably best to consider them like file handles, because the Wimp uses them in a way more akin to file opening/closing. e.g. a font handle is ‘opened’ by a call to FNwimp_getfont()
as above - and the font ought to be ‘closed’ after its last use in the application using PROCwimp_losefont
. For example:
PROCwimp_losefont(fonthandle%)
As with Dynamic Areas, any font handles not already closed when the application quits are automatically closed by Dr Wimp. However, this is best regarded as a fall-back facility and there are many circumstances where it is best for you to carry out specific font handle closures during the normal program run.
The text-plotting wimp-functions
Once the font has been chosen the most useful text-plotting wimp-functions to use will be:
PROCwimp_plotwindowtext
()
PROCwimp_plotwindowtexth
()
These are a complementary pair with only the “h” in the name signifying that the latter requires the font to be defined as a font handle - and therefore the former requires the font to be defined as a name. Both of these have many parameters:
PROCwimp_plotwindowtext(window%,t$,f$,sizex,sizey,align%,x%,y%, fr%,fg%,fb%,br%,bg%,bb%,minx%,miny%,maxx%,maxy%, scalex,scaley,blending%)
PROCwimp_plotwindowtexth(window%,t$,font%,align%,x%,y%, fr%,fg%,fb%,br%,bg%,bb%,minx%,miny%,maxx%,maxy%, scalex,scaley,blending%)
The only differences between them, as you will expect, is that the first one has f$,sizex,sizey
to define the font/size combination by name, whereas the second has just font%
for the font handle.
The other common parameters are:
window%
is the window in which to plot the text;
t$
is the text string to plot;
align%
determines the justification. 0 means left justified, 1 means centred and 2 means right justified (all with respect to the plotting position);
x%,y%
is the required plotting position in work area OS coordinates (remember, visible y values will be negative);
fr%,fg%,fb%
define the foreground text colour (0-255 Red, Green, Blue);
br%,bg%,bb%
define the background text colour (0-255 Red, Green, Blue);
minx%,miny%,maxx%,maxy%
is the clipping rectangle passed through from the
PROCuser_redraw
parameters (as with the graphics display cases in Section 2.19);
scalex,scaley
are the text scales required in the x/y directions with, as before, 1 meaning 100%;
blending%
is a flag determining whether ‘font blending’ is to be used - see a little later below.
A typical sequence placed inside PROCuser_redraw
might be:
IF window%=main% THEN
PROCwimp_plotwindowtexth(main%,"Test",trinity12%,0,50,-50,0,0,0, 255,255,255,minx%,miny%,maxx%,maxy%,1,1,0)
ENDIF
which would plot the text “Test” in the main% window, left-aligned at 50,-50 with Blak text on a White background without enlargement/reduction and without font blending. The font name/size combination would be captured by the font handle trinity12%
- provided by a call to FNwimp_getfont()
previously.
With both this pair of text-plotting calls, if the specified font cannot be found then the default font of “Trinity.Medium” will be substituted automatically. This is an essential safeguard in case the user of your application does not have your specified font on his/her machine.
Note that if the ‘font name’ version is used, a call to FNwimp_getfont()
is made automatically within the call (and PROCwimp_losefont
afterwards) so the “f” version of the pair is always a little quicker.
(Note: With the ability to scale text in outline fonts, it becomes much easier to offer a ‘Print preview’ option in your applications.)
Additional wimp-functions
As with the graphics plotting cases in Section 2.19, there is a pair of wimp-functions mainly used for plotting text during printing. They are:
PROCwimp_plottext()
PROCwimp_plottexth()
i.e. without the “window” in the name. The details are similar to their “window” counterparts but without the window handle parameter, plus a need to use ‘coordinates with respect to the bottom left of the screen/paper.
Checking the text size before plotting
There is also a pair of wimp-functions giving the to-be-plotted width and height of the text. They are:
FNwimp_gettextsize()
FNwimp_gettextsizeh()
These functions - which include the ability to get the size of scaled text - are very useful when it is required to place text precisely - although the align%
parameter in the plotting wimp-functions is sufficient in many cases where only alignment in the x-direction is needed.
Note that FNwimp_gettextsize
returns a size of 0 if it cannot find the specified font, but FNwimp_gettextsizeh
will produce a fatal error if the specified font handle cannot be found.
‘Font blending’
The parameter blending%
is in all four of the text plotting wimp-functions introduced above and it has been set to 0 in the example call shown earlier.
If blending%
is given any other value then - if the computer on which the Dr Wimp application is running uses Font Manager called 3.35 or higher - ‘font blending’ will take place. This means that RISCOS will automatically attempt to blend the text with the background colour(s), producing a significantly better visual result.
However, there is a potential price to pay for this facility as it can slow down the text rendering process. In practice, therefore, blending is best not used in all text plotting operations - but rather kept to those cases where blending will be worthwhile i.e. typically when text plotting takes place over a non-white background e.g. text superimposed on a graphic.
It is for this reason that ‘font blending’ has been introduced as an option.
Modifying the text with control codes
Not just simple strings of text can be plotted with the above wimp-functions. In addition, strings of control code sequences can be inserted into the string-to-be-plotted to turn underlining on and off, change the font, or change the font colour within the line of text. DrWimp provides functions to produce these control strings. For example:
t$="Cat "+FNwimp_fontunderline(1)+"dog"+ FNwimp_fontunderline(0)+" hen."
when plotted would result in the word “dog” being underlined. Note the positioning of the spaces between the three words so they don't get underlined as well.
An example of turning the text red:
t$="Cat "+FNwimp_fontcolour(255,0,0,221,221,221)+"dog."
would make the word “dog.” become red (on an anti-aliased background of light grey - standard Wimp colour 1). The text can be turned black again afterwards with 0,0,0,221,221,221
.
And for changing the font (assuming homerton20%
is a font handle already found):
t$="Cat "+FNwimp_fontchangeh(homerton20%)+"dog."
would make the word “dog.” appear in the font whose handle is homerton20%
.
Note that there isn't an equivalent FNwimp_fontchange
(no “h”) as the control sequence only works with font handles.
Any combination of these can be used to produce the effect you want. Note that if you plot a string and the end of it is in red for example, then the next line you plot will be in black again. There is no need to change the colour back to black as all effects such as colours, underlining and changing font apply for that plotting action only.
Matching the ‘desktop font’
Finally, there are two functions which also plot text but they use the current ‘desktop font’ - which, depending on the RISC OS Version, may or may not be an outline font.
The functions are PROCwimp_deskplotwindowtext
()
and PROCwimp_deskplottext
()
and they both need RISCOS Version 3.50 or higher. Their parameters are straightforward if you have read the whole of this Section and you will note that there is not a ‘font blending’ option.
These two functions are useful for matching the fonts displayed directly onto the window with that used, for example, by default in icons.
Top of page Back to Contents Previous Next